/*
*    Qizx/open 3.0 beta
*
* This code is the open-source version of Qizx.
* Copyright (C) 2004-2009 Axyana Software -- All rights reserved.
*
* The contents of this file are subject to the Mozilla Public License 
*  Version 1.1 (the "License"); you may not use this file except in 
*  compliance with the License. You may obtain a copy of the License at
*  http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
*  WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
*  for the specific language governing rights and limitations under the
*  License.
*
* The Initial Developer of the Original Code is Xavier Franc - Axyana Software.
*
*/
using System;
namespace System.Qizx.Api.FullText
{
	
	
	/// <summary> Customizable part of the full-text scoring algorithm.
	/// <p>
	/// This interface defines:<ul>
	/// <li>Weighting formulas for different types of FT selections (basic term, all,
	/// any, mild-not...)
	/// <li>Scoring formulas for different types of FT selections
	/// <li>Normalization of the final value, so that it is between 0 and 1
	/// </ul>
	/// </summary>
	public interface Scorer
	{
		// ---------- weighting: called when initializing a query
		
		/// <summary> Computes the weight associated with a simple word.</summary>
		/// <param name="inverseDocFrequency">inverse of the fraction of documents that
		/// contain this term
		/// </param>
		/// <returns> the computed weighting of simple term. The default
		/// implementation is: 1 + log(inverseDocFrequency)
		/// </returns>
		float normWord(float inverseDocFrequency);
		
		/// <summary> Computes the weight norm associated with a conjunction ('ftand' or
		/// 'all') of full-text selections. The default weight norm is the sum of
		/// squared sub-weights power -1/2.
		/// </summary>
		/// <param name="subWeights">weight values computed for sub-selections.
		/// </param>
		/// <returns> the computed weighting.
		/// </returns>
		float normAll(float[] subWeights);
		
		/// <summary> Computes the weight norm associated with a disjunction ('ftor' or 'any') of
		/// full-text selections.
		/// </summary>
		/// <param name="subWeights">weight values computed for sub-selections.
		/// </param>
		/// <returns> the normed weighting. The default implementation is a weighted
		/// average of the sum of sub-weights and their maximum value.
		/// </returns>
		float normOr(float[] subWeights);
		
		// ---------- scoring: called at run-time
		
		/// <summary> Computes the score of a single word.</summary>
		/// <param name="norm">normalized weight of word (as computed by {@link #normWord(float)}).
		/// </param>
		/// <param name="termFrequency">relative term frequency in the current document
		/// (number of occurrences divided by average number of occurrences in all
		/// documents).
		/// </param>
		/// <returns> the computed score. The default implementation is termFrequency
		/// multiplied by 'norm'.
		/// </returns>
		float scoreWord(float norm, float termFrequency);
		
		/// <summary> Computes the score of a conjunction ('ftand' or 'all') of
		/// full-text selections.
		/// </summary>
		/// <param name="subScores">weight values computed for sub-selections.
		/// </param>
		/// <returns> the computed weighting. The default implementation is the sum of
		/// scores.
		/// </returns>
		float scoreAll(float[] subScores);
		
		/// <summary> Computes the score of a disjunction ('ftor' or 'any') of full-text
		/// selections.
		/// </summary>
		/// <param name="subScores">weight values computed for sub-selections.
		/// </param>
		/// <param name="scoreCount">number of values in scores
		/// </param>
		/// <returns> the computed score. The default implementation is a weighted
		/// average of the sum of sub-scores and their maximum value.
		/// </returns>
		float scoreOr(float[] subScores, int scoreCount);
		/// <summary> Normalizes a score so that its value is between 0 and 1</summary>
		/// <param name="rawScore">a positive value possibly greater than 1
		/// </param>
		float normalizeScore(float rawScore);
	}
}